Repository navigation
[WIP]: Documentation restructuring - #4874
Draft
CsatariGergely wants to merge 3 commits into
Draft
CsatariGergely wants to merge 3 commits into
CsatariGergely wants to merge 3 commits into
Conversation
Adding the structure agreed in kptdev#4451 Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>
CsatariGergely
requested review from
a team
and
a balanced review from Copilot
November 13, 2026 12:19
CsatariGergely
requested review from
efiacor,
kispaljr,
liamfallon and
mozesl-nokia
as code owners
November 13, 2026 12:19
✅ Deploy Preview for kptdocs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
CsatariGergely
marked this pull request as draft
November 13, 2026 12:19
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved issues break reference navigation and existing schema URLs, while the published Plan schema does not match the CLI output.
3 open issues
What changed in this PR
This PR begins restructuring kpt documentation into topic- and task-based sections, following #4451’s move away from a book-centered layout.
Changes:
- Adds section scaffolding for concepts, installation, getting started, guides, FAQ, and contributing.
- Relocates reference documentation, adds legacy page aliases, and updates links and generation paths.
- Restores sidebar navigation and uses the documentation tree on the homepage.
| File | Description |
|---|---|
scripts/generate-schema.sh |
Updates schema output paths. |
documentation/README.md |
Updates documentation-link examples. |
documentation/layouts/partials/sidebar.html |
Adds sidebar rendering and homepage root selection. |
documentation/layouts/partials/sidebar-tree.html |
Removes the sidebar-disabling override. |
documentation/content/en/reference/_index.md |
Removes the former reference landing page. |
documentation/content/en/guides/3-way-merge.md |
Updates reference links. |
documentation/content/en/faq.md |
Updates the function reference link. |
documentation/content/en/documentation/8-contributing/documentation-contribution/error-messages-style-guide.md |
Adds an error-style-guide entry. |
documentation/content/en/documentation/8-contributing/documentation-contribution/_index.md |
Adds a documentation-contribution entry. |
documentation/content/en/documentation/8-contributing/code-contribution.md |
Adds a code-contribution entry. |
documentation/content/en/documentation/8-contributing/_index.md |
Adds the contributing section scaffold. |
documentation/content/en/documentation/7-FAQ/_index.md |
Adds the FAQ section scaffold. |
documentation/content/en/documentation/6-references/schema/resource-list/_index.md |
Relocates the reference and adds a legacy alias. |
documentation/content/en/documentation/6-references/schema/plan/plan.yaml |
Publishes the Plan schema at the new path. |
documentation/content/en/documentation/6-references/schema/plan/_index.md |
Relocates the reference and adds a legacy alias. |
documentation/content/en/documentation/6-references/schema/kptfile/kptfile.yaml |
Publishes the YAML schema at the new path. |
documentation/content/en/documentation/6-references/schema/kptfile/kptfile.json |
Publishes the JSON schema at the new path. |
documentation/content/en/documentation/6-references/schema/kptfile/_index.md |
Relocates the reference and adds a legacy alias. |
documentation/content/en/documentation/6-references/schema/function-result-list/_index.md |
Relocates the reference and adds a legacy alias. |
documentation/content/en/documentation/6-references/schema/crd-status-convention/_index.md |
Relocates the reference and adds a legacy alias. |
documentation/content/en/documentation/6-references/schema/_index.md |
Relocates the schema section and adds an alias. |
documentation/content/en/documentation/6-references/cli/pkg/update/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/pkg/tree/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/pkg/init/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/pkg/get/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/pkg/diff/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/pkg/cat/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/pkg/_index.md |
Moves package commands into the new reference tree. |
documentation/content/en/documentation/6-references/cli/live/status/_index.md |
Relocates documentation and updates the apply link. |
documentation/content/en/documentation/6-references/cli/live/migrate/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/live/install-resource-group/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/live/init/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/live/destroy/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/live/apply/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/live/_index.md |
Moves deployment commands into the new reference tree. |
documentation/content/en/documentation/6-references/cli/fn/source/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/fn/sink/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/fn/render/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/fn/eval/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/fn/doc/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/fn/_index.md |
Moves function commands into the new reference tree. |
documentation/content/en/documentation/6-references/cli/alpha/wasm/push/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/alpha/wasm/pull/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/alpha/wasm/_index.md |
Moves WASM commands into the new reference tree. |
documentation/content/en/documentation/6-references/cli/alpha/sync/get/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/alpha/sync/delete/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/alpha/sync/create/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/alpha/sync/_index.md |
Moves sync commands into the new reference tree. |
documentation/content/en/documentation/6-references/cli/alpha/live/plan/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/alpha/live/_index.md |
Moves alpha deployment commands into the new tree. |
documentation/content/en/documentation/6-references/cli/alpha/license/info/_index.md |
Relocates command documentation and adds an alias. |
documentation/content/en/documentation/6-references/cli/alpha/license/_index.md |
Moves license commands into the new reference tree. |
documentation/content/en/documentation/6-references/cli/alpha/_index.md |
Moves alpha commands into the new reference tree. |
documentation/content/en/documentation/6-references/cli/_index.md |
Relocates the CLI overview and updates command links. |
documentation/content/en/documentation/6-references/annotations/local-config/_index.md |
Relocates the annotation reference and adds an alias. |
documentation/content/en/documentation/6-references/annotations/depends-on/_index.md |
Relocates the annotation reference and adds an alias. |
documentation/content/en/documentation/6-references/annotations/apply-time-mutation/_index.md |
Relocates the reference and updates fragment links. |
documentation/content/en/documentation/6-references/annotations/_index.md |
Relocates the annotation overview and updates links. |
documentation/content/en/documentation/6-references/_index.md |
Adds the replacement reference landing page. |
documentation/content/en/documentation/5-guides/working-with-kpt-packages/updating-a-package/effective-customizations.md |
Adds an effective-customizations placeholder. |
documentation/content/en/documentation/5-guides/working-with-kpt-packages/updating-a-package/_index.md |
Adds a package-update section scaffold. |
documentation/content/en/documentation/5-guides/working-with-kpt-packages/rendering-a-package.md |
Adds a package-rendering placeholder. |
documentation/content/en/documentation/5-guides/working-with-kpt-packages/publishing-a-package.md |
Adds a package-publishing placeholder. |
documentation/content/en/documentation/5-guides/working-with-kpt-packages/getting-a-package.md |
Adds a package-fetching placeholder. |
documentation/content/en/documentation/5-guides/working-with-kpt-packages/exploring-a-package.md |
Adds a package-exploration placeholder. |
documentation/content/en/documentation/5-guides/working-with-kpt-packages/excluding-files-with-krmignore.md |
Adds a file-exclusion placeholder. |
documentation/content/en/documentation/5-guides/working-with-kpt-packages/editing-a-package.md |
Adds a package-editing placeholder. |
documentation/content/en/documentation/5-guides/working-with-kpt-packages/deploying-packages.md |
Adds a package-deployment placeholder. |
documentation/content/en/documentation/5-guides/working-with-kpt-packages/creating-a-package.md |
Adds a package-creation placeholder. |
documentation/content/en/documentation/5-guides/working-with-kpt-packages/composing-a-package.md |
Adds a package-composition placeholder. |
documentation/content/en/documentation/5-guides/working-with-kpt-packages/_index.md |
Adds the package-guides section. |
documentation/content/en/documentation/5-guides/working-with-functions/imperative-function-execution.md |
Adds an imperative-execution placeholder. |
documentation/content/en/documentation/5-guides/working-with-functions/function-results.md |
Adds a function-results placeholder. |
documentation/content/en/documentation/5-guides/working-with-functions/developing-functions.md |
Adds a function-development placeholder. |
documentation/content/en/documentation/5-guides/working-with-functions/declarative-function-execution.md |
Adds a declarative-execution placeholder. |
documentation/content/en/documentation/5-guides/working-with-functions/_index.md |
Adds the function-guides section. |
documentation/content/en/documentation/5-guides/krm-function-developer-guide.md |
Adds a KRM developer-guide placeholder. |
documentation/content/en/documentation/5-guides/ci-user-guide.md |
Adds a CI user-guide placeholder. |
documentation/content/en/documentation/5-guides/advanced-topics/variant-constructor-pattern.md |
Adds a variant-constructor placeholder. |
documentation/content/en/documentation/5-guides/advanced-topics/value-propagation-pattern.md |
Adds a value-propagation placeholder. |
documentation/content/en/documentation/5-guides/advanced-topics/understanding-3-way-merge.md |
Adds a three-way-merge placeholder. |
documentation/content/en/documentation/5-guides/advanced-topics/tenant-onboarding.md |
Adds a tenant-onboarding placeholder. |
documentation/content/en/documentation/5-guides/advanced-topics/_index.md |
Adds the advanced-topics section. |
documentation/content/en/documentation/5-guides/_index.md |
Adds the guides section scaffold. |
documentation/content/en/documentation/4-getting-started/system-requirements.md |
Adds a system-requirements placeholder. |
documentation/content/en/documentation/4-getting-started/quickstart.md |
Adds a quickstart placeholder. |
documentation/content/en/documentation/4-getting-started/_index.md |
Adds the getting-started section scaffold. |
documentation/content/en/documentation/3-intallation/source.md |
Adds a source-installation placeholder. |
documentation/content/en/documentation/3-intallation/homebrew.md |
Adds a Homebrew-installation placeholder. |
documentation/content/en/documentation/3-intallation/docker.md |
Adds a Docker-installation placeholder. |
documentation/content/en/documentation/3-intallation/_index.md |
Adds the installation section scaffold. |
documentation/content/en/documentation/2-concepts/workflows.md |
Adds a workflows placeholder. |
documentation/content/en/documentation/2-concepts/packages.md |
Adds a package-concepts placeholder. |
documentation/content/en/documentation/2-concepts/functions.md |
Adds a function-concepts placeholder. |
documentation/content/en/documentation/2-concepts/_index.md |
Adds the concepts section scaffold. |
documentation/content/en/documentation/1-overview/_index.md |
Adds an overview section placeholder. |
documentation/content/en/documentation/_index.md |
Adds the new documentation root. |
documentation/content/en/book/08-ci-user-guide/_index.md |
Updates the deployment reference link. |
documentation/content/en/book/06-deploying-packages/_index.md |
Updates deployment and annotation reference links. |
documentation/content/en/book/05-developing-functions/_index.md |
Updates the annotation reference link. |
documentation/content/en/book/04-using-functions/_index.md |
Updates function and annotation reference links. |
documentation/content/en/book/03-packages/_index.md |
Updates package command reference links. |
documentation/content/en/book/02-concepts/_index.md |
Updates CLI and annotation reference links. |
documentation/content/en/book/01-getting-started/_index.md |
Updates function command reference links. |
documentation/content/en/_index.md |
Changes homepage reference-link selection. |
documentation/assets/scss/_sidebar-left.scss |
Updates the sidebar icon font and weight. |
cli/main.go |
Points documentation generation at relocated sources. |
AGENTS.md |
Updates documentation paths in contributor guidance. |
Review effort: Balanced
|
|
||
| To get familiar with kpt, the best way to start is with the first 4 chapters of the kpt [Book]({{% relref "book" %}}). | ||
| Furthermore it is useful to check the [references]({{% relref "reference" %}}) and the catalog of [selected krm functions](https://catalog.kpt.dev). | ||
| Furthermore it is useful to check the [references]({{ with or (site.GetPage "/documentation/6-references") (site.GetPage "/reference") }}{{ .RelPermalink }}{{ end }}) and the catalog of [selected krm functions](https://catalog.kpt.dev). |
Comment on lines
+4
to
+5
| weight: 1 | ||
| list_pages: true |
Comment on lines
+42
to
+43
| $SWAGGER_CMD generate spec -m -w api/kptfile/v1 -o documentation/content/en/documentation/6-references/schema/kptfile/kptfile.yaml | ||
| $SWAGGER_CMD generate spec -m -w api/kptfile/v1 -o documentation/content/en/documentation/6-references/schema/kptfile/kptfile.json |
|
Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>
Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.




Adding the structure agreed in #4451
Closes: #4451